<html xmlns="http://www.w3.org/1999/xhtml">
<head>
</head>
<body>

<!-- ===================================================================== -->
<!-- = XML information goes here                                         = -->
<!-- ===================================================================== -->
<lzelement title="LzEvent">
    <lztier>LFC</lztier>
    <lzcategory>Event</lzcategory>
    <lzshortdesc>
        The sender in Laszlo's point-to-point event system.
    </lzshortdesc>
    <lzapi>api-lzevent.xml</lzapi>
    <seealso>delegate</seealso>
</lzelement>

<p>Events underly most of the functionality in Laszlo  applications. 
Unlike events in similar systems, Laszlo's events are point-to-point, meaning that there is no general broadcast mechanism for events, and events do not trickle up or down the instance hierarchy. Instead, objects called <a href="delegate.html">delegates</a> <a href="delegate.html#meth-register">register</a> for events, and if they try to register for an event that doesn't exist yet, the system creates the event. Because of the loose type requirements in Laszlo script, calling an event that no delegate is listening for (and which therefore hasn't been created) has no effect. This allows objects to publish many more events than they actually need to create at runtime.
</p>

<p>There are two syntaxes with which you can specify an event handler for a system-defined event associated with an object: in the tag used to create that object, or by using the <code>event</code> keyword in a 
<tagname>method</tagname> tag associated with the object.</p>

<p>To specify an event handler in an object-creation tag, simply include it like any other attribute.  For example,</p>

<example class="code" extract="false">
&lt;view onMouseOver="doSomething()"&gt;
  &lt;method name="doSomething"&gt;
    // code to be executed when mouse is over the view
  &lt;/method&gt;
&lt;/view&gt;
</example>

<p>If you use the <code>event</code> keyword in the method definition, you do not need to include the handler in the tag that creates the object.</p>

<example class="code" extract="false">
&lt;view&gt;
 &lt;method event="onMouseOver"&gt;
   // code to be executed when the mouse is over the view
 &lt;/method&gt;
&lt;/view&gt;
</example>

<p> The above two examples are functionally equivalent.  Using the <code>event</code> keyword, however, can often lead to more readable code because it removes clutter from the object creation tag.</p> 

<p>The following example illustrates how to create custom events.</p>

<example class="program"
         title="A simple example of publishing and listening for a custom event">
&lt;canvas height="40"&gt;
  &lt;simplelayout/&gt;
  &lt;button name="eventSender" 
          <em>onmouseover="this.customevent.sendEvent()"
          onmouseout="this.customevent.sendEvent()"/&gt;</em>
  &lt;view bgcolor="red" width="20" height="20" oninit="this.setupDelegate()"&gt;
    &lt;method name="setupDelegate"&gt;
      this.del = new LzDelegate( this, "respondToEvent" );
      <em>this.del.register( eventSender , "customevent" );</em>
    &lt;/method&gt;
    &lt;method name="respondToEvent"&gt;
      this.setAttribute('x', this.x + 10);
    &lt;/method&gt;
  &lt;/view&gt;
&lt;/canvas&gt;
</example>

<p>
Events can be sent with a single argument, which usually conveys information about the property that changed. Events and <a href="attribute.html">attributes</a> often work as pairs, and in fact, the default behavior of the <a href="node.html#meth-setAttribute">setAttribute</a> method is to set the named property and send the event called "on" + property. This is general mechanism that updates constraints in a Laszlo program and the convention is widely used: for instance, when a view changes its <attribute>x</attribute> position, it sends the event <event>onx</event> with the new value for its <attribute>x</attribute> property.
</p>

<example class="program"
         title="Event sending in response to setting an attribute">
&lt;canvas height="40"&gt;
  &lt;simplelayout/&gt;
  &lt;button name="eventSender" 
          <em>onmouseover="this.setAttribute('avalue', this.avalue + 10)"
          onmouseout="this.setAttribute('avalue', this.avalue + 5)"</em>&gt;
    &lt;attribute name="avalue" value="0"/&gt;
  &lt;/button&gt;
  &lt;view bgcolor="red" width="20" height="20" oninit="this.setupDelegate()"&gt;
    &lt;method name="setupDelegate"&gt;
      this.del = new LzDelegate(this, "respondToEvent");
      this.del.register(eventSender, <em>"onavalue"</em>);
    &lt;/method&gt;
    &lt;method name="respondToEvent" args="v"&gt;
      this.setAttribute('x' , v);
    &lt;/method&gt;
  &lt;/view&gt;
&lt;/canvas&gt;
</example>

<p>
Finally, event-handlers are related to events. Event handlers are recognized in the schema as attributes whose value is a script to run when the object runs the event. In the code above, for instance, the code that calls the <method>setupDelegate</method> method is executed when the view sends its <event>oninit</event> event.</p>
</body>
</html>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2001-2004 Laszlo Systems, Inc.  All Rights Reserved.              *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->
